home *** CD-ROM | disk | FTP | other *** search
CCCCFFFFLLLLOOOOWWWW((((1111)))) SSSSiiiilllliiiiccccoooonnnn GGGGrrrraaaapppphhhhiiiiccccssss CCCCFFFFLLLLOOOOWWWW((((1111)))) NNNNAAAAMMMMEEEE cflow - generate C flowgraph SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ccccfffflllloooowwww [----rrrr] [----iiiixxxx] [----iiii____ ] [----ddddnum] files DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The _c_f_l_o_w command analyzes a collection of C, yacc, and lex files and attempts to build a graph charting the external references. Files suffixed with ....yyyy, ....llll, ....cccc, or ....iiii are yacced, lexed, and compiled as appropriate. The results are collected and turned into a graph which is displayed upon the standard output. If the environment variable _XPG is defined, _c_f_l_o_w operates in conformance with the X/Open XPG4 specifications. The format of the output may differ in accordance to the XPG4 standards. In addition to the ----DDDD, ----IIII, and ----UUUU options [which are interpreted just as they are by _c_c(1) and _c_p_p(1)], the following options are interpreted by _c_f_l_o_w: ----rrrr Reverse the ``caller:callee'' relationship producing an inverted listing showing the callers of each function. The listing is sorted in lexicographical order by callee. ----iiiixxxx Include external and static data symbols. The default is to include only functions in the flowgraph. If _XPG is set, then there could be 0 or more spaces between -i and x. ----iiii____ Include names that begin with an underscore. The default is to exclude these functions (and data if -_i_x is used). If _XPG is set, then there could be 0 or more spaces between -i and _. ----ddddnum The _n_u_m decimal integer indicates the depth at which the flowgraph is cut off. By default this is a very large number. Attempts to set the cutoff depth to a nonpositive integer are ignored. If _XPG is set, then there could be 0 or more spaces between -d and num. ----ssssuuuupppppppprrrreeeessssssss suppressfile Eliminates reporting of functions named in the file _s_u_p_p_r_e_s_s_f_i_l_e. The format of the file is discussed below. ----nnnnaaaarrrrrrrroooowwww The output is narrowed by removing the function type output, changing all filenames to show only the filename (no directory path) and by changing indentation to be two spaces (indentation is not changed for ----rrrr ). ----bbbbaaaasssseeee basefunction The flow reported starts at the function _b_a_s_e_f_u_n_c_t_i_o_n and only reports descendents of that function. (This option ignored for ----rrrr Page 1 Release 6.4 CCCCFFFFLLLLOOOOWWWW((((1111)))) SSSSiiiilllliiiiccccoooonnnn GGGGrrrraaaapppphhhhiiiiccccssss CCCCFFFFLLLLOOOOWWWW((((1111)))) ) ----rrrraaaawwww Instead of being processed into a cflow output, the raw cflow information from the C compiler is passed directly to the output. The format of this data is described below. ----rrrraaaawwwwiiiinnnn _f_i_l_e Pass in to _c_f_l_o_w for formatting the _f_i_l_e as if it were the output of cflow -raw. The file must be in the proper format: if it is not, the result will likely be chaos. ----vvvv Print on standard error the arguments passed to sub-passes and such other information as seems interesting. GGGGRRRRAAAAPPPPHHHH FFFFOOOORRRRMMMMAAAATTTT Each line of output begins with a reference number, followed by a suitable number of tabs indicating the level, then the name of the global symbol followed by a colon and its definition. Normally only function names that do not begin with an underscore are listed (see the ----iiii options below). For information extracted from C source, the definition consists of an abstract type declaration (e.g., cccchhhhaaaarrrr ****), and, delimited by angle brackets, the name of the source file and the line number where the definition was found. Definitions extracted from object files indicate type information (if possible), followed by the name of the file in which the symbol appeared enclosed in angle brackets. Leading underscores in C-style external names are deleted. Once a definition of a name has been printed, subsequent references to that name contain only the reference number of the line where the definition may be found. For undefined references, only <<<<>>>> is printed. As an example, given the following in _f_i_l_e._c: int i; static int localstat; int main(int argc, char **argv) { f(); g(argc,argv); f(); return(0); } int f() { i = h(); localstat = j(); return 0; } Page 2 Release 6.4 CCCCFFFFLLLLOOOOWWWW((((1111)))) SSSSiiiilllliiiiccccoooonnnn GGGGrrrraaaapppphhhhiiiiccccssss CCCCFFFFLLLLOOOOWWWW((((1111)))) the command cflow -ix file.c produces the output 1 main: int (int , char *(*)), <file.c 4> 2 g: int (), <file.c 7> 3 f: int (), <file.c 12> 4 i: int, <file.c 1> 5 h: int (), <file.c 14> 6 localstat<file.c,0>: int, <file.c 2> 7 j: int (), <file.c 15> When the nesting level becomes too deep, the output of _c_f_l_o_w can be piped to _p_r(1), using the ----eeee option, to compress the tab expansion to something less than every eight spaces. To keep file-local static variables and functions from being confused from variables and functions in other files, statics are shown with the compilation unit name and a unique number. In the above, _l_o_c_a_l_s_t_a_t<_f_i_l_e._c,_0> is an example of this convention. To be clear about functions or variables defined inside functions, the file and line of the actual definition is mentioned and, if it is a #include-ed file, the name of the compilation-unit file is mentioned in parentheses. Example: <stati1.h (in stati1.c) 2> Static variables defined inside a function and function-local variables and parameters are never mentioned in the _c_f_l_o_w output. When analyzing the structure of a program, focusing on what a single function does (_m_y_f_u_n_c for example) is sometimes helpful. In such a case a command like cflow -narrow -base myfunc -suppress libcstuff file.c may be useful. This reports only on _m_y_f_u_n_c, it keeps the output narrow to avoid line-wrapping, and if libc.so functions are named in the file _l_i_b_c_s_t_u_f_f those (presumably well known and therefore uninteresting for your analysis) will not be shown. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS Most diagnostic messages come from the C compiler. The C compiler is not the same as _c_c. Diagnostics may also come from _y_a_c_cor _l_e_x, and generally appear on standard error. Page 3 Release 6.4 CCCCFFFFLLLLOOOOWWWW((((1111)))) SSSSiiiilllliiiiccccoooonnnn GGGGrrrraaaapppphhhhiiiiccccssss CCCCFFFFLLLLOOOOWWWW((((1111)))) The following come from _c_f_l_o_w: SSSSttttaaaattttiiiicccc yyyy ddddeeeeffffiiiinnnneeeedddd iiiinnnn <<<<ssssttttaaaattttiiii1111....hhhh ((((iiiinnnn ssssttttaaaattttiiii1111....cccc)))) 2222>>>> <<<<ssssttttaaaattttiiii1111....hhhh ((((iiiinnnn ssssttttaaaattttiiii2222....cccc)))) 2222>>>> <<<<ssssttttaaaattttiiii1111....hhhh ((((iiiinnnn ssssttttaaaattttiiii3333....cccc)))) 2222>>>> means that the variable _y is defined as static in the listed files at the listed line numbers. The parenthesized name is the source file being compiled: whenever the source file of the message is a #include-ed file _c_f_l_o_w shows the name of both the the included file and the file name presented to the C compiler front-end. ccccfffflllloooowwww WWWWaaaarrrrnnnniiiinnnngggg:::: RRRReeeeddddeeeeffffiiiinnnniiiittttiiiioooonnnnssss ooooffff aaaannnnooootttthhhheeeerrrrzzzzeeeedddd :::: <<<<sssstttt2222....cccc 2222>>>> <<<<sssstttt3333....cccc 3333>>>> means that the variable _a_n_o_t_h_e_r_z_e_d is defined in the listed source files at the specified line numbers. ccccfffflllloooowwww WWWWaaaarrrrnnnniiiinnnngggg:::: EEEExxxxtttteeeerrrrnnnnaaaallll zzzzeeeedddd <<<<sssstttt2222....cccc 1111>>>> iiiissss ssssttttaaaattttiiiicccc iiiinnnn <<<<sssstttt1111....cccc 1111>>>> means that the external variable _z_e_d is static in the listed file(s), which is a little unusual. ccccfffflllloooowwww WWWWaaaarrrrnnnniiiinnnngggg:::: DDDDeeeeccccllllaaaarrrraaaattttiiiioooonnnn ttttyyyyppppeeee mmmmiiiissssmmmmaaaattttcccchhhh xxxx:::: means that the variable _x is declared with different types in different source files. The types and declaration locations are shown in the message. SSSSUUUUPPPPPPPPRRRREEEESSSSSSSS OOOOPPPPTTTTIIIIOOOONNNN FFFFIIIILLLLEEEE FFFFOOOORRRRMMMMAAAATTTT Any line beginning with whitespace (blank, tab, or newline) is considered a comment and all characters in the line (up through the next newline) are ignored. If a line begins with other than whitespace, all characters up to the first whitespace character are considered part of a name-to-be- suppressed. (Any characters on the line beginning at the first whitespace character are considered comment and (up through the next newline) are ignored.) The file of names to be ignored can contain as many names as desired. A file containing zero lines or zero names-to-be-suppressed is also allowed. Now we turn to a description of the processing of any name-to-be- suppressed that may have been found by the above character scanning. Each name to be suppressed is processed by _r_e_g_c_m_p(3G) and _r_e_g_e_x(3G) and _c_f_l_o_w supplies a leading "^" and a trailing "$". See the _r_e_g_e_x(3G) man page for further information about the available matching capabilities. For example, to match strlen, one could use (strings are left justified in the file but indented here so they stand out): strlen To match all functions beginning with str, one could use str.* To match all functions with zzyzz in the name, one could use .*zzyzz.* Page 4 Release 6.4 CCCCFFFFLLLLOOOOWWWW((((1111)))) SSSSiiiilllliiiiccccoooonnnn GGGGrrrraaaapppphhhhiiiiccccssss CCCCFFFFLLLLOOOOWWWW((((1111)))) RRRRAAAAWWWW DDDDAAAATTTTAAAA FFFFOOOORRRRMMMMAAAATTTT A cflow raw reference record (the format may change from release to release) is a line of white-space separated fields. Each record documents a single cflow instance and is terminated with a new-line. All data is in plain text. All numbers are in decimal. ddddaaaattttaaaa----rrrreeeeccccoooorrrrdddd----aaaaddddddddrrrreeeessssssss is the integer internal address of a compiler structure as a decimal number. Not used by cflow. iiiiddddeeeennnnttttiiiiffffiiiieeeerrrr is the name of a variable or function or is "{" if this is the beginning of a compilation unit, or is "}" if this is the end of a compilation unit. ccccooooddddeeee is one of D,M,A, or R. D if this is a declaration. M if this is a modification of the variable. A if the address is taken. R if this is a reference to the variable or function. If this is the beginning or end of a compilation unit, the code is D. ffffiiiilllleeeennnnaaaammmmeeee is the source file name where found. lllliiiinnnneeee----nnnnuuuummmmbbbbeeeerrrr is the line number where the reference was found. If this is the beginning or end of a compilation unit, line-number is 0. ccccoooolllluuuummmmnnnn----nnnnuuuummmmbbbbeeeerrrr is the column number where the reference was found. If this is the beginning or end of a compilation unit, column-number is 0. ttttyyyyppppeeee is one of B, F, or N. B means this is a function body (so _c_o_d_e above is D). F means this is a function, not a data variable, and not a function body (_c_o_d_e may be D, as a declaration, or A, or R). N means this is not a function. If this is the beginning or end of a compilation unit, the type is is N. ssssccccooooppppeeee----lllleeeevvvveeeellll is an integer giving the current local scope level. Local (inner) scopes with no declarations are not interesting so they are not counted. If this is the beginning or end of a compilation unit, the scope is 0. iiiinnnncccclllluuuuddddeeee----ddddeeeepppptttthhhh is an integer giving the current #include nesting depth. If this is the beginning or end of a compilation unit, the depth is 0. ddddaaaattttaaaa----ttttyyyyppppeeee is the data type represented as a C declaration with whitespace in the declaration replaced by '~' (tilde) characters. If this is the beginning or end of a compilation unit, data-type is "?" or, if available, the full path name of the compilation unit. Page 5 Release 6.4 CCCCFFFFLLLLOOOOWWWW((((1111)))) SSSSiiiilllliiiiccccoooonnnn GGGGrrrraaaapppphhhhiiiiccccssss CCCCFFFFLLLLOOOOWWWW((((1111)))) ssssttttaaaattttiiiicccc----ffffllllaaaagggg is S if the item is a static function or variable or N if it is not. If this is the beginning or end of a compilation unit, the static- flag is N. ddddeeeeccccllll----ffffllllaaaagggg is C if this is a deClaration, F if this is a deFinition, or N if this is neither. If this is the beginning or end of a compilation unit, the decl-flag is N. FFFFIIIILLLLEEEESSSS /usr/bin/cflow /usr/lib/ecfe SSSSEEEEEEEE AAAALLLLSSSSOOOO cc(1), lex(1), yacc(1), pr(1). OOOOPPPPTTTTIIIIOOOONNNN NNNNOOOOTTTTEEEESSSS The ----aaaaccccpppppppp option is ignored. The ----nnnnooooccccpppppppp option is ignored. However, _c_f_l_o_w accepts files suffixed with ._i as C files. Also the ----nnnnoooossssttttddddiiiinnnncccc option does not work. _c_f_l_o_w attempts to understand many of the options normally passed to _c_c(1). Many options are irrelevant to _c_f_l_o_w so they are silently ignored. Others must simply be avoided on the _c_f_l_o_w command line. Since the compiler predefines know and created by _c_c are not identical to those built into _c_f_l_o_w, it is wise to use ----sssshhhhoooowwww option to _c_c to create a script file with the -D and -U options shown as being passed to the compiler. Invoke _c_f_l_o_w via the script (there are too many -D items to do this command creation reliably on the command line). Edit the script to remove options that _c_f_l_o_w does not understand. Some #pragmas known to the regular _c_c command are not known to _c_f_l_o_w, so useless warnings about unknown pragmas may appear at times. Page 6 Release 6.4 
